<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Chapter 15. Caching</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
<link rel="home" href="index.html" title="Smarty 3 Manual">
<link rel="up" href="smarty.for.programmers.html" title="Part III. Smarty For Programmers">
<link rel="prev" href="api.test.install.html" title="testInstall()">
<link rel="next" href="caching.multiple.caches.html" title="Multiple Caches Per Page">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr><th colspan="3" align="center">Chapter 15. Caching</th></tr>
<tr>
<td width="20%" align="left">
<a accesskey="p" href="api.test.install.html">Prev</a> </td>
<th width="60%" align="center">Part III. Smarty For Programmers</th>
<td width="20%" align="right"> <a accesskey="n" href="caching.multiple.caches.html">Next</a>
</td>
</tr>
</table>
<hr>
</div>
<div class="chapter" title="Chapter 15. Caching">
<div class="titlepage"><div><div><h2 class="title">
<a name="caching"></a>Chapter 15. Caching</h2></div></div></div>
<div class="toc">
<p><b>Table of Contents</b></p>
<dl>
<dt><span class="sect1"><a href="caching.html#caching.setting.up">Setting Up Caching</a></span></dt>
<dt><span class="sect1"><a href="caching.multiple.caches.html">Multiple Caches Per Page</a></span></dt>
<dt><span class="sect1"><a href="caching.groups.html">Cache Groups</a></span></dt>
<dt><span class="sect1"><a href="caching.cacheable.html">Controlling Cacheability of Output</a></span></dt>
<dd><dl>
<dt><span class="sect2"><a href="caching.cacheable.html#cacheability.sections">Cacheability of Template Section</a></span></dt>
<dt><span class="sect2"><a href="caching.cacheable.html#cacheability.tags">Cacheability of Tags</a></span></dt>
<dt><span class="sect2"><a href="caching.cacheable.html#cacheability.variables">Cacheability of Variables</a></span></dt>
<dt><span class="sect2"><a href="caching.cacheable.html#cacheability.plugins">Cacheability of Plugins</a></span></dt>
</dl></dd>
<dt><span class="sect1"><a href="caching.custom.html">Custom Cache Implementation</a></span></dt>
</dl>
</div>
<p>
   Caching is used to speed up a call to <a class="link" href="api.display.html" title="display()"><code class="varname">display()</code></a> or <a class="link" href="api.fetch.html" title="fetch()"><code class="varname">fetch()</code></a> by saving its output
   to a file. If a
   cached version of the call is available, that is displayed instead of
   regenerating the output. Caching can speed things up tremendously,
   especially templates with longer computation times. Since the output of
   <a class="link" href="api.display.html" title="display()"><code class="varname">display()</code></a> or
   <a class="link" href="api.fetch.html" title="fetch()"><code class="varname">fetch()</code></a> is cached,
   one cache file could conceivably be made up
   of several template files, config files, etc.
   </p>
<p>
   Since templates are dynamic, it is important to be careful what you are
   caching and for how long. For instance, if you are displaying the front page
   of your website that does not change its content very often, it might work
   well to cache this page for an hour or more. On the other hand, if you are
   displaying a page with a timetable containing new information by the
   minute, it would not make sense to cache this page.
   </p>
<div class="sect1" title="Setting Up Caching">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="caching.setting.up"></a>Setting Up Caching</h2></div></div></div>
<p>
    The first thing to do is enable caching by setting <a class="link" href="variable.caching.html" title="$caching">
    <em class="parameter"><code>$caching</code></em></a> to one of <code class="literal">Smarty::CACHING_LIFETIME_CURRENT</code> or <code class="literal">Smarty::CACHING_LIFETIME_SAVED</code>.
   </p>
<div class="example">
<a name="id450552"></a><p class="title"><b>Example 15.1. Enabling caching</b></p>
<div class="example-contents"><pre class="programlisting">

&lt;?php
require('Smarty.class.php');
$smarty = new Smarty;

// uses the value of $smarty-&gt;cacheLifetime() to determine
// the number of seconds a cache is good for
$smarty-&gt;setCaching(Smarty::CACHING_LIFETIME_CURRENT);

$smarty-&gt;display('index.tpl');
?&gt;

    </pre></div>
</div>
<br class="example-break"><p>
    With caching enabled, the function call to
    <code class="literal">display('index.tpl')</code> will render
    the template as usual, but also saves a copy of its output to a file (a
    cached copy) in the
    <a class="link" href="variable.cache.dir.html" title="$cache_dir"><em class="parameter"><code>$cache_dir</code></em></a>.
    On the next call to <code class="literal">display('index.tpl')</code>, the cached copy
    will be used instead of rendering the template again.
   </p>
<div class="note" title="Technical Note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Technical Note</h3>
<p>
     The files in the
     <a class="link" href="variable.cache.dir.html" title="$cache_dir"><em class="parameter"><code>$cache_dir</code></em></a>
     are named similar to the template name.
     Although they end in the <code class="filename">.php</code> extention, they are not
     intended to be directly executable. Do not edit these files!
    </p>
</div>
<p>
    Each cached page has a limited lifetime determined by <a class="link" href="variable.cache.lifetime.html" title="$cache_lifetime"><em class="parameter"><code>$cache_lifetime</code></em></a>.
    The default value is 3600 seconds, or one hour. After that time expires, the
    cache is regenerated. It is possible to give individual caches their own
    expiration time by setting
    <a class="link" href="variable.caching.html" title="$caching"><em class="parameter"><code>$caching</code></em></a> to <code class="literal">Smarty::CACHING_LIFETIME_SAVED</code>.
    See <a class="link" href="variable.cache.lifetime.html" title="$cache_lifetime"><em class="parameter"><code>$cache_lifetime</code></em></a>
    for more details.
   </p>
<div class="example">
<a name="id450667"></a><p class="title"><b>Example 15.2. Setting $cache_lifetime per cache</b></p>
<div class="example-contents"><pre class="programlisting">

&lt;?php
require('Smarty.class.php');
$smarty = new Smarty;

// retain current cache lifetime for each specific display call
$smarty-&gt;setCaching(Smarty::CACHING_LIFETIME_SAVED);

// set the cache_lifetime for index.tpl to 5 minutes
$smarty-&gt;setCacheLifetime(300);
$smarty-&gt;display('index.tpl');

// set the cache_lifetime for home.tpl to 1 hour
$smarty-&gt;setCacheLifetime(3600);
$smarty-&gt;display('home.tpl');

// NOTE: the following $cache_lifetime setting will not work when $caching
// is set to Smarty::CACHING_LIFETIME_SAVED.
// The cache lifetime for home.tpl has already been set
// to 1 hour, and will no longer respect the value of $cache_lifetime.
// The home.tpl cache will still expire after 1 hour.
$smarty-&gt;setCacheLifetime(30); // 30 seconds
$smarty-&gt;display('home.tpl');
?&gt;

    </pre></div>
</div>
<br class="example-break"><p>
    If <a class="link" href="variable.compile.check.html" title="$compile_check">
    <em class="parameter"><code>$compile_check</code></em></a> is enabled (default),
    every template file and config file that is involved with the cache file is
    checked for modification. If any of the files have been modified since the
    cache was generated, the cache is immediately regenerated. This is a computational
    overhead, so for optimum performance set
    <a class="link" href="variable.compile.check.html" title="$compile_check"><em class="parameter"><code>$compile_check</code></em>
    </a> to <code class="constant">FALSE</code>.
   </p>
<div class="example">
<a name="id450727"></a><p class="title"><b>Example 15.3. Disabling $compile_check</b></p>
<div class="example-contents"><pre class="programlisting">

&lt;?php
require('Smarty.class.php');
$smarty = new Smarty;

$smarty-&gt;setCaching(Smarty::CACHING_LIFETIME_CURRENT);
$smarty-&gt;setCompileCheck(false);

$smarty-&gt;display('index.tpl');
?&gt;

    </pre></div>
</div>
<br class="example-break"><p>
    If <a class="link" href="variable.force.compile.html" title="$force_compile">
    <em class="parameter"><code>$force_compile</code></em></a> is enabled,
    the cache files will always be regenerated. This effectively disables caching,
    however this also seriously degrades performance.
    <a class="link" href="variable.force.compile.html" title="$force_compile"><em class="parameter"><code>$force_compile</code></em>
    </a> is meant to be used for
    <a class="link" href="chapter.debugging.console.html" title="Chapter 10. Debugging Console">debugging</a>
    purposes. The appropriate way to disable caching is to set <a class="link" href="variable.caching.html" title="$caching"><em class="parameter"><code>$caching</code></em>
    </a> to Smarty::CACHING_OFF.
   </p>
<p>
    The <a class="link" href="api.is.cached.html" title="isCached()"><code class="varname">isCached()</code></a>
    function
    can be used to test if a template has a valid cache or not. If you have a
    cached template that requires something like a database fetch, you can use
    this to skip that process.
   </p>
<div class="example">
<a name="id450804"></a><p class="title"><b>Example 15.4. Using isCached()</b></p>
<div class="example-contents"><pre class="programlisting">

&lt;?php
require('Smarty.class.php');
$smarty = new Smarty;

$smarty-&gt;setCaching(Smarty::CACHING_LIFETIME_CURRENT);

if(!$smarty-&gt;isCached('index.tpl')) {
    // No cache available, do variable assignments here.
    $contents = get_database_contents();
    $smarty-&gt;assign($contents);
}

$smarty-&gt;display('index.tpl');
?&gt;

    </pre></div>
</div>
<br class="example-break"><p>
    You can keep parts of a page dynamic (disable caching) with the <a class="link" href="language.function.nocache.html" title="{nocache}"><code class="varname">{nocache}{/nocache}</code></a>
    block function, the <a class="link" href="language.function.insert.html" title="{insert}"><code class="varname">{insert}</code></a>
    function, or by using the <code class="literal">nocache</code> parameter for most template functions.
   </p>
<p>  
    Let's
    say the whole page can be cached except for a banner that is displayed down
    the side of the page. By using the
    <a class="link" href="language.function.insert.html" title="{insert}"><code class="varname">{insert}</code></a>
    function for the banner, you
    can keep this element dynamic within the cached content. See the
    documentation on
    <a class="link" href="language.function.insert.html" title="{insert}"><code class="varname">{insert}</code></a>
    for more details and examples.
   </p>
<p>
    You can clear all the cache files with the <a class="link" href="api.clear.all.cache.html" title="clearAllCache()"><code class="varname">clearAllCache()</code></a>
    function, or
    individual cache files
    <a class="link" href="caching.groups.html" title="Cache Groups">and groups</a>
    with the <a class="link" href="api.clear.cache.html" title="clearCache()"><code class="varname">clearCache()</code></a> function.
   </p>
<div class="example">
<a name="id450900"></a><p class="title"><b>Example 15.5. Clearing the cache</b></p>
<div class="example-contents"><pre class="programlisting">

&lt;?php
require('Smarty.class.php');
$smarty = new Smarty;

$smarty-&gt;setCaching(Smarty::CACHING_LIFETIME_CURRENT);

// clear only cache for index.tpl
$smarty-&gt;clearCache('index.tpl');

// clear out all cache files
$smarty-&gt;clearAllCache();

$smarty-&gt;display('index.tpl');
?&gt;

    </pre></div>
</div>
<br class="example-break">
</div>
</div>
<div class="navfooter">
<hr>
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left">
<a accesskey="p" href="api.test.install.html">Prev</a> </td>
<td width="20%" align="center"><a accesskey="u" href="smarty.for.programmers.html">Up</a></td>
<td width="40%" align="right"> <a accesskey="n" href="caching.multiple.caches.html">Next</a>
</td>
</tr>
<tr>
<td width="40%" align="left" valign="top">testInstall() </td>
<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
<td width="40%" align="right" valign="top"> Multiple Caches Per Page</td>
</tr>
</table>
</div>
</body>
</html>
